Repository navigation
docs: a generated MCP tool reference; fix contradictory living docs - #82
Merged
Merged
Conversation
- scripts/mcp-tools-doc.ts writes the MCP server README's tool reference (all 102 tools: scopes, kind, approval, first sentence) from `defineTools()`; `pnpm check` and CI fail when it is stale. The README's hand-written "deterministic order" list named about 45 of them. - Counts and lists that drift now point to their source: "20 semantic MCP tools" (README, twice) → over 100 with a link to the reference; CLI command lists → `cloudhal --help` / the CLI reference; scopes → `KEY_SCOPES`/`PERSON_SCOPES`; lazy namespaces → `namespaces.ts`. - Stale statements: comments and schedules guides said their Studio screens were still being built; Studio has 19 languages, not en/tr; `patch_draft` patches pages, not article bodies; the add-capability skill described a `capabilities/` runtime that never shipped; the starter README misdated the `entryPath` fallback; jsonschema 0.59; the `RENDER_CHECK_SCRIPT` path; the server instructions' unconditional approval sentence. - ADR-0003, ADR-0004, ADR-0006: dated addenda for decisions the code did not follow. - DESIGN.md: Collections settings, live-site links and pending changes. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Madraka <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Generated MCP tool reference
scripts/mcp-tools-doc.tswritespackages/mcp-server/README.md#tool-referencefromdefineTools(): all 102 tools in server order, with scopes, kind (read / write / destructive), approval (always a person / depends on the call / by mode) and the first sentence of the description. Angle brackets are escaped outside code spans, and a cut never leaves a code span open.node scripts/mcp-tools-doc.ts --checkis inpnpm checkand CI.The README's old "deterministic order" list named only about 45 of the tools.
Living docs fixed (from an audit of about 33 items)
Principle: a number or list that drifts points to its source instead of copying it. RFCs, CHANGELOGs and reports are left alone.
README.md--help/ the CLI reference; Studio "en/tr" → 19 languages; skills and guides → linksREADME.md,CONTRIBUTING.md,AGENTS.mdpnpm check→ oneAGENTS.mdhelp.ts; thetranslateskill added; lazy namespaces →namespaces.ts; jsonschema 0.59docs/agents/README.mdpatch_draftis for pages, not article bodies; tool count → the referencepackages/agent-runtime/README.mdKEY_SCOPES/PERSON_SCOPES, rolespackages/cli/README.md--help, the reference, common commandsdocs/guides/comments.md,schedules.mdtranslations-weblate.md,analytics-privacy.md.agents/skills/add-capabilitycapabilities/runtime that never shipped → today's processstudio-uiskill, DESIGN.mdpnpm kumo lsstarters/blog/README.mdentryPathfallback was kept in 0.3.11 (it was restored in 0.3.13)code-structure.md,server-instructions.ts,packages/api/README.md/pendingroute and Bearer authChecks
mcp-tools-doc --checkand the size ratchet pass.mcp.test.ts9/9.🤖 Generated with Claude Code